feat(cdp): accept an idempotency key on the transactional email route by mayteio · Pull Request #120510 · PostHog/posthog

mayteio · 2026-10-20T16:28:54Z

Problem

A caller of the transactional email API cannot retry safely. When a request times out after cdp-api queued the email, the retry sends it a second time.
#117787 tried to fix this in Django and was closed. Django cannot tell whether cdp-api queued the email, so the key belongs at cdp-api's queue boundary.

Changes

cdp-api's transactional email route accepts an optional idempotency_key from Django. It reserves the key in the shared IdempotencyKeys store from #120446 before it queues the send.

Request	Answer
First request with a key	`202`, the new `invocation_id`, `replayed: false`
Same key and same request within 24 hours	`202`, the first `invocation_id`, `replayed: true`. Nothing queues.
Same key, different request	`422 idempotency_key_reused`
Same key while the first request still queues	`409 idempotency_key_in_flight`
Key sent while the store is unavailable	`503 idempotency_unavailable`. Nothing queues.

The key is scoped to the team. A hash of the workflow, recipient, distinct id and data detects reuse for a different request.
The key check runs before the quota check, so a retry of a send that already went out gets its first answer after the team hits its quota.
A queue failure or a quota rejection frees the key, so the caller's retry can send.
cdp_transactional_email_requests_total gains the replayed and idempotency_* outcomes.
Requests without a key behave as before. Django does not send a key until #120392, so this PR changes nothing for callers by itself.

How did you test this code?

Test rationale: five cases extend the existing transactional email block in cdp-api.serial.test.ts, against the real Valkey. A retry returns the first send and queues once. A reused key returns 422. A retry during a held queue write returns 409. A queue failure frees the key for the retry. No store means 503 and nothing queued. No existing test covered a repeated request.

The end-to-end demo of the whole API, with this route and the Django half, is on #120392.

Release status

This change is behind a feature flag and is not available to users

Docs update

None. The endpoint is flagged and has no public docs yet.

🤖 Agent context

Autonomy: Human-driven (agent-assisted)

Agent: Claude Code (PostHog Desktop cloud task), Claude Opus 5.5

Skills invoked: /writing-tests, /stacking-prs, /writing-pr-descriptions.
Split out of feat(messaging): add an idempotency key to the transactional email api #120392 so each PR stays in one merge-queue lane: this PR is Node only, and feat(messaging): add an idempotency key to the transactional email api #120392 is Django only.
Stack, bottom to top: #120446 (shared store), then #120510 (cdp-api route), then #117287 (webhook trigger), then #120392 (Django API). Land it bottom-first: every layer is then in a single merge-queue lane when it merges.

Created with PostHog Desktop

🤖 Generated with Claude Code

github-actions · 2026-10-20T16:31:36Z

🤖 CI report

✅ Trunk lane — non-backend lane

This PR is assigned to the non-backend lane. It does not run backend Python tests and may merge in parallel with PRs in other lanes.

⚠️

Duplication (Python) — 71 new duplicated blocks (worst 339 tokens)

New Python code duplication introduced by this branch. Fails at 70+ tokens in app code, or 150+ tokens when both copies live in test files. Advisory while the gate proves itself: extract a shared helper instead of copying.

⚠️

Duplication (TypeScript) — 11 new duplicated blocks (worst 592 tokens)

New TypeScript code duplication introduced by this branch. Fails at 70+ tokens in app code, or 150+ tokens when both copies live in test files. Advisory while the gate proves itself: extract a shared helper instead of copying.

First copy	Second copy	Lines	Tokens
`frontend/src/lib/utils/liquid.ts:7`	`nodejs/src/cdp/utils/liquid.ts:88`	100	592
`frontend/src/lib/oauthScopes.generated.ts:12`	`services/mcp/src/lib/oauth-scopes.generated.ts:12`	253	521
`services/mcp/scripts/generate-tools.ts:2224`	`services/mcp/scripts/generate-tools.ts:2249`	20	194
`frontend/src/scenes/dashboard/DashboardItems.test.tsx:441`	`frontend/src/scenes/dashboard/DashboardItems.test.tsx:493`	33	161
`services/mcp/scripts/generate-tools.ts:2202`	`services/mcp/scripts/generate-tools.ts:2230`	13	156
`services/mcp/scripts/yaml-config-schema.ts:190`	`services/mcp/scripts/yaml-config-schema.ts:611`	32	113
`services/mcp/scripts/yaml-config-schema.ts:201`	`services/mcp/src/tools/toolDefinitions.ts:23`	21	94
`frontend/src/lib/utils/eventUsageLogic.ts:1624`	`frontend/src/scenes/onboarding/shared/wizard-sync/installationProgressLogic.ts:175`	28	92
`frontend/src/products.tsx:2707`	`products/error_tracking/manifest.tsx:108`	14	87
`products/workflows/frontend/Broadcasts/broadcastTestSendLogic.ts:96`	`products/workflows/frontend/TemplateLibrary/messageTemplateTestSendLogic.ts:63`	22	77
`frontend/src/scenes/dashboard/dashboardLogic.tsx:4818`	`frontend/src/scenes/dashboard/dashboardLogic.tsx:4835`	11	76

⚠️

Comment density — 4% of added code lines are comments (5 of 132)

This section warns when comments are more than 3% of the code lines a PR adds, and alerts above 6%. Before agent-assisted PRs, the typical share was about 2%. Only full-line comments count. Docstrings, generated files, snapshots, migrations, and workflow files are left out.

Comments that restate the code, record how the change came about, or narrate the next line add noise for the next reader. Keep the comments that explain a reason the code cannot show, and remove the rest. See .agents/skills/writing-code-comments/SKILL.md for the house rules.

Files with the most added comment lines:

File	Comment lines	Added lines
`nodejs/src/cdp/cdp-api.ts`	3	50
`nodejs/src/cdp/cdp-api.serial.test.ts`	1	75
`nodejs/src/cdp/services/hogflows/transactional-email.ts`	1	7

This check does not block merging. It updates on every push and clears when the share drops.

posthog · 2026-10-20T16:35:10Z

PostHog Review · Deep · reviewed `6e40f5f`

Nothing to post.

Step	Status	Result
Prepare the diff	done	2 files, 1 chunk
Pick perspectives	done	3 perspectives
Run review passes	done	0 issues
Merge overlapping findings	done	0 → 0
Validate findings	done
Publish	done	Nothing to post

trunk-io · 2026-10-20T17:08:10Z

Failed Test	Failure Summary	Logs
`postgres parity createPerson`	A database operation failed because it attempted to use a PostgreSQL connection pool after the pool had been closed.	Logs ↗︎

_{View Full Report ↗︎ ⋅ Docs}

parameterai · 2026-10-20T17:43:37Z

Risk: No findings

This PR adds optional idempotency-key handling to cdp-api's transactional-email route: the key is reserved in a team-scoped Valkey store before queueing, retries replay the first invocation, and quota-rejected or failed queue writes release the key. I found no security vulnerability: the route's JWT auth is unchanged, keys are team-scoped and hashed, the reserve is atomic, and the release/mark-queued scripts check invocation ownership so late releases cannot free another request's key. The known residual (a possible duplicate after a 60-second crash window) is a documented same-caller correctness trade-off, not a security boundary.

_{Sentinel reviewed 6e40f5f · Review settings}

cdp-api's transactional email route accepts an optional idempotency_key from Django and reserves it in the shared IdempotencyKeys store before it checks the quota and queues the send. A repeat of the same request returns the first invocation id with replayed: true, a key reused for a different request returns 422, a repeat while the first request still queues returns 409, and an unavailable store returns 503. A queue failure or quota rejection frees the key. Django does not send the key yet, so this route behaves as before until the Django change lands. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Generated-By: PostHog Desktop Task-Id: 37f4fab5-e683-4a35-a865-b07749cbaa38

New commits were pushed — dismissing the stamphog approval from an earlier head. Re-add the trigger label to request a fresh review.

stamphog

Approved.

The risky changes have owning-team authorship and STRONG familiarity, with focused tests and no unresolved substantive review concerns. The reported database-pool test failure does not identify a defect introduced by this diff.

Author wrote 75% of the modified lines and has 27 merged PRs in these paths (familiarity STRONG).

Gate mechanics and policy version

Gate		Result
prerequisites	✓	all clear
deny-list	✓	no deny categories matched
size	✓	67L, 2F substantive, 163L/3F incl. docs/generated/snapshots — within ceiling
tier	✓	T1-agent / T1c-medium (163L, 3F, single-area, feat)
stamphog 2.6.0		`.stamphog/policy.yml` @ `164b489` · reviewed head `164b489`

trunk-io · 2026-10-21T09:51:55Z

This pull request is queued for merge as part of 117287, which will merge 120446, 120510, 117287.

trunk-io · 2026-10-21T10:20:01Z

This pull request was merged into master as part of stacked PR 117287.

deployment-status-posthog · 2026-10-21T10:54:41Z

Deploy status

Environment	Status	Deployed At	Workflow
dev	✅ Deployed	2026-10-21 10:54 UTC	Run
prod-us	✅ Deployed	2026-10-21 11:05 UTC	Run
prod-eu	✅ Deployed	2026-10-21 11:07 UTC	Run

mayteio self-assigned this Oct 20, 2026

mayteio added this pull request to stack #120511 October 20, 2026 16:29

mayteio mentioned this pull request Oct 20, 2026

feat(messaging): add an idempotency key to the transactional email api #120392

Merged

mayteio force-pushed the posthog/cdp-transactional-email-idempotency branch from 35deda7 to 9c19d1f Compare October 20, 2026 16:36

mayteio removed this pull request from stack #120511 October 20, 2026 16:49

mayteio added this pull request to stack #120528 October 20, 2026 16:50

This was referenced Oct 20, 2026

feat(cdp): add a shared idempotency key store for workflows #120446

Merged

feat(workflows): idempotency key on the webhook trigger #117287

Merged

mayteio force-pushed the posthog/cdp-transactional-email-idempotency branch from 9c19d1f to 6e40f5f Compare October 20, 2026 17:30

mayteio marked this pull request as ready for review October 20, 2026 17:31

pr-assigner-resolver-posthog Bot requested a review from a team October 20, 2026 17:32

This comment was marked as outdated.

Sign in to view

This was referenced Oct 20, 2026

Grill Resend parity: React templates, delivery guarantee, sender-scoped keys Silthus/posthog#525

Closed

Transactional email SDK contract for posthog-python and posthog-node #120921

Open

mayteio force-pushed the posthog/cdp-transactional-email-idempotency branch from 6e40f5f to 164b489 Compare October 21, 2026 09:26

mayteio added the stamphog Request AI approval (no full review) label Oct 21, 2026 — with PostHog

stamphog Bot approved these changes Oct 21, 2026

View reviewed changes

trunk-io Bot merged commit 4e75c08 into master Oct 21, 2026
254 of 256 checks passed

trunk-io Bot deleted the posthog/cdp-transactional-email-idempotency branch October 21, 2026 10:19

Silthus mentioned this pull request Oct 21, 2026

Spec Resend parity and slice it into PRs Silthus/posthog#531

Closed

Silthus mentioned this pull request Oct 21, 2026

Build strand: the code-content send API (Resend parity) Silthus/posthog#535

Open

10 of 11 tasks

mayteio mentioned this pull request Oct 21, 2026

feat: send transactional email from posthog templates PostHog/posthog-python#1093

Merged

3 of 5 tasks

Navigation Menu

Repository navigation

feat(cdp): accept an idempotency key on the transactional email route - #120510

feat(cdp): accept an idempotency key on the transactional email route#120510
trunk-io[bot] merged 1 commit into
posthog/cdp-idempotency-keysfrom
posthog/cdp-transactional-email-idempotency

mayteio commented Oct 20, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

posthog Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

trunk-io Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

This comment was marked as outdated.

Uh oh!

parameterai Bot commented Oct 20, 2026 •

edited

Loading

Uh oh!

stamphog Bot left a comment

Uh oh!

trunk-io Bot commented Oct 21, 2026

Uh oh!

Uh oh!

trunk-io Bot commented Oct 21, 2026

Uh oh!

deployment-status-posthog Bot commented Oct 21, 2026 •

edited

Loading

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

mayteio commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Changes

How did you test this code?

Release status

Docs update

🤖 Agent context

Uh oh!

github-actions Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🤖 CI report

Uh oh!

posthog Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PostHog Review · Deep · reviewed 6e40f5f

Uh oh!

trunk-io Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

parameterai Bot commented Oct 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

stamphog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

trunk-io Bot commented Oct 21, 2026

Uh oh!

Uh oh!

trunk-io Bot commented Oct 21, 2026

Uh oh!

deployment-status-posthog Bot commented Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploy status

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

mayteio commented Oct 20, 2026 •

edited

Loading

github-actions Bot commented Oct 20, 2026 •

edited

Loading

posthog Bot commented Oct 20, 2026 •

edited

Loading

PostHog Review · Deep · reviewed `6e40f5f`

trunk-io Bot commented Oct 20, 2026 •

edited

Loading

parameterai Bot commented Oct 20, 2026 •

edited

Loading

deployment-status-posthog Bot commented Oct 21, 2026 •

edited

Loading